/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License"),
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup TeeTrusted
 * @{
 *
 * @brief TEE（Trusted Excution Environment）可信执行环境API。
 *
 * 提供安全能力API，例如可信存储、加解密及可信时间等，用于可信应用程序开发。
 *
 * @since 20
 */

/**
 * @file tee_object_api.h
 *
 * @brief 提供可信存储API。
 *
 * 开发者可以使用API以实现可信存储功能。
 *
 * @library NA
 * @kit TEEKit
 * @include <TEEKit/tee_object_api.h>
 * @syscap SystemCapability.Tee.TeeClient
 * @since 20
 */

#ifndef __TEE_OBJECT_API_H
#define __TEE_OBJECT_API_H

#include "tee_defines.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 定义HANDLE_NULL，用于表示句柄的缺失。
 *
 * @since 20
 */
#define TEE_HANDLE_NULL 0x00000000

/**
 * @brief 枚举TEE_ObjectHandle的密钥用途。
 *
 * @since 20
 */
enum Usage_Constants {
    /** 该对象的密钥是可提取的。 */
    TEE_USAGE_EXTRACTABLE = 0x00000001,
    /** 用于加密。 */
    TEE_USAGE_ENCRYPT     = 0x00000002,
    /** 用于解密。 */
    TEE_USAGE_DECRYPT     = 0x00000004,
    /** 用于哈希计算。 */
    TEE_USAGE_MAC         = 0x00000008,
    /** 用于创建签名。 */
    TEE_USAGE_SIGN        = 0x00000010,
    /** 用于签名验证。 */
    TEE_USAGE_VERIFY      = 0x00000020,
    /** 用于密钥派生。 */
    TEE_USAGE_DERIVE      = 0x00000040,
    /** 用于对象初始化，默认分配所有权限。 */
    TEE_USAGE_DEFAULT     = 0xFFFFFFFF,
};

/**
 * @brief 定义TEE_ObjectHandle标志所指向对象的信息，例如对象是否为持久对象或已初始化。
 *
 * @since 20
 */
enum Handle_Flag_Constants {
    /** 该对象是持久对象。 */
    TEE_HANDLE_FLAG_PERSISTENT      = 0x00010000,
    /** 该对象已初始化。 */
    TEE_HANDLE_FLAG_INITIALIZED     = 0x00020000,
    /** 保留字段。 */
    TEE_HANDLE_FLAG_KEY_SET         = 0x00040000,
    /** 保留字段。 */
    TEE_HANDLE_FLAG_EXPECT_TWO_KEYS = 0x00080000,
};

/**
 * @brief 定义值属性标识符标志。
 *
 * @since 20
 */
#define TEE_ATTR_FLAG_VALUE  0x20000000

/**
 * @brief 定义公有属性标识符标志。
 *
 * @since 20
 */
#define TEE_ATTR_FLAG_PUBLIC 0x10000000

/**
 * @brief 检查属性是否为缓冲区类型。
 *
 * @since 20
 */
#define TEE_ATTR_IS_BUFFER(attribute_id) ((((attribute_id) << 2) >> 31) == 0)

/**
 * @brief 检查属性是否为值类型。
 *
 * @since 20
 */
#define TEE_ATTR_IS_VALUE(attribute_id)  ((((attribute_id) << 2) >> 31) == 1)

/**
 * @brief 检查属性是否受保护。
 *
 * @since 20
 */
#define TEE_ATTR_IS_PROTECTED(attribute_id) ((((attribute_id) << 3) >> 31) == 0)

/**
 * @brief 检查属性是否为公有属性。
 *
 * @since 20
 */
#define TEE_ATTR_IS_PUBLIC(attribute_id)    ((((attribute_id) << 3) >> 31) == 1)

/**
 * @brief 从指向对象的TEE_ObjectHandle结构体中的TEE_Attribute获取缓冲区属性。
 *
 * TEE_Attribute结构体中的成员必须是ref类型。\n
 * 如果TEE_Attribute是私有的，则对象的Usage_Constants必须包含TEE_USAGE_EXTRACTABLE。
 *
 * @param object 指示对象的句柄。
 * @param attributeID 指示要获取的属性的ID，例如TEE_ObjectAttribute。
 * 属性ID也可以自定义。
 * @param buffer 指向存储获取的属性的缓冲区的指针。
 * @param size 指向存储内容长度的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法在对象中找到TEE_Attribute或对象未初始化。\n
 *         TEE_ERROR_SHORT_BUFFER：缓冲区太小，无法存储获取的内容。
 * @since 20
 */
TEE_Result TEE_GetObjectBufferAttribute(TEE_ObjectHandle object, uint32_t attributeID, void *buffer, size_t *size);

/**
 * @brief 从对象的TEE_Attribute获取值属性。
 *
 * TEE_Attribute结构体的成员必须是值类型。\n
 * 如果TEE_Attribute是私有的，则对象的Usage_Constants必须包含TEE_USAGE_EXTRACTABLE。
 *
 * @param object 指示对象的句柄。
 * @param attributeID 指示要获取的属性的ID，例如TEE_ObjectAttribute。
 * 属性ID也可以自定义。
 * @param a 指向用属性字段a填充的占位符的指针。
 * @param b 指向用属性字段b填充的占位符的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_ITEM_NOT_FOUND：无法在对象中找到TEE_Attribute或对象未初始化。\n
 *         TEE_ERROR_ACCESS_DENIED：TEE_Attribute是私有的，但对象的Usage_Constants不包含TEE_USAGE_EXTRACTABLE标志。
 * @since 20
 */
TEE_Result TEE_GetObjectValueAttribute(TEE_ObjectHandle object, uint32_t attributeID, uint32_t *a, uint32_t *b);

/**
 * @brief 关闭TEE_ObjectHandle对象。
 *
 * 该对象可以是持久对象或临时对象。
 *
 * @param object 指示要关闭的TEE_ObjectHandle对象。
 *
 * @since 20
 */
void TEE_CloseObject(TEE_ObjectHandle object);

/**
 * @brief 分配一个未初始化的对象来存储密钥。
 *
 * 必须指定objectType和maxObjectSize。
 *
 * @param objectType 表示要创建的对象类型，值为TEE_ObjectType。
 * @param maxObjectSize 表示对象的最大字节数。
 * @param object 表示指向新创建对象句柄的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_OUT_OF_MEMORY：如果内存不足。\n
 *         TEE_ERROR_NOT_SUPPORTED：不支持该对象类型。
 * @since 20
 */
TEE_Result TEE_AllocateTransientObject(uint32_t objectType, uint32_t maxObjectSize, TEE_ObjectHandle *object);

/**
 * @brief 释放之前使用TEE_AllocateTransientObject分配的临时对象。
 *
 * 调用此函数后，句柄变为无效，所有分配的资源被释放。\n
 * TEE_FreeTransientObject和TEE_AllocateTransientObject是一对使用的函数。
 *
 * @param object 表示要释放的TEE_ObjectHandle。
 *
 * @since 20
 */
void TEE_FreeTransientObject(TEE_ObjectHandle object);

/**
 * @brief 将一个未初始化的对象重置为其分配后的初始状态。
 *
 * 可以使用一个已分配但尚未初始化或用来存储密钥的对象来存储密钥。
 *
 * @param object 表示要重置的TEE_ObjectHandle。
 *
 * @since 20
 */
void TEE_ResetTransientObject(TEE_ObjectHandle object);

/**
 * @brief 用 TA 传递的 <b>attrs</b> 参数中的对象属性填充未初始化的对象。
 *
 * 对象必须是未初始化的。\n
 * <b>attrs</b> 参数由TA传递。
 *
 * @param object 表示已创建但未初始化对象的句柄。
 * @param attrs 表示指向对象属性数组的指针，数组可以包含一个或多个TEE_Attribute。
 * @param attrCount 表示属性数组中的成员数。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_BAD_PARAMETERS：检测到不正确或不一致的属性值。
 * @since 20
 */
TEE_Result TEE_PopulateTransientObject(TEE_ObjectHandle object, TEE_Attribute *attrs, uint32_t attrCount);

/**
 * @brief 初始化缓冲区类型的TEE_Attribute。
 *
 * TEE_Attribute结构中的成员必须是ref类型。
 *
 * @param attr 表示指向已初始化的TEE_Attribute的指针。
 * @param attributeID 表示分配给TEE_Attribute的ID。
 * @param buffer 表示指向用于存储待分配内容的缓冲区的指针。
 * @param length 表示分配值的长度，单位为字节。
 *
 * @since 20
 */
void TEE_InitRefAttribute(TEE_Attribute *attr, uint32_t attributeID, void *buffer, size_t length);

/**
 * @brief 初始化一个TEE_Attribute。
 *
 * @param attr 表示指向已初始化的TEE_Attribute的指针。
 * @param attributeID 表示分配给TEE_Attribute的ID。
 * @param a 表示要分配给TEE_Attribute成员a的值。
 * @param b 表示要分配给TEE_Attribute成员b的值。
 *
 * @since 20
 */
void TEE_InitValueAttribute(TEE_Attribute *attr, uint32_t attributeID, uint32_t a, uint32_t b);

/**
 * @brief 生成一个随机密钥或密钥对，并将生成的密钥填充到临时密钥对象中。
 *
 * @param object 表示用于保存生成密钥的临时对象。
 * @param keySize 表示密钥的字节数。
 * @param params 表示指向密钥生成参数的指针。
 * @param paramCount 表示密钥生成所需的参数数量。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_BAD_PARAMETERS：生成的密钥类型与临时对象能保存的密钥类型不匹配。
 * @since 20
 */
TEE_Result TEE_GenerateKey(TEE_ObjectHandle object, uint32_t keySize, TEE_Attribute *params, uint32_t paramCount);

/**
 * @brief 获取对象数据部分的信息，包括数据部分的总长度和数据流的当前位置信息。
 *
 * @param object 表示对象的句柄。
 * @param pos 表示数据流的位置。
 * @param len 表示数据流的长度。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         如果操作失败，返回其他错误码。
 * @since 20
 */
TEE_Result TEE_InfoObjectData(TEE_ObjectHandle object, uint32_t *pos, uint32_t *len);

/**
 * @brief 获取TEE_ObjectInfo。
 *
 * 此函数获取TEE_ObjectInfo并将获取的信息复制到预分配的空间，
 * 该空间由objectInfo指针指向。
 *
 * @param object 表示对象的句柄。
 * @param objectInfo 表示指向获取的TEE_ObjectInfo的指针。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_CORRUPT_OBJECT：对象已损坏，将关闭该对象句柄。\n
 *         TEE_ERROR_STORAGE_NOT_AVAILABLE：对象存储在当前不可访问的存储区域。
 * @since 20
 */
TEE_Result TEE_GetObjectInfo1(TEE_ObjectHandle object, TEE_ObjectInfo *objectInfo);

/**
 * @brief 将已初始化对象的TEE_Attribute分配给未初始化对象。
 *
 * 此函数将一个未初始化对象填充为TEE_Attribute。\n
 * 即将srcobject的TEE_Attribute复制到destobject。\n
 * 两个对象的TEE_Attribute类型和ID必须匹配。
 *
 * @param destObject 表示未初始化的对象。
 * @param srcObject 表示已初始化的对象。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_CORRUPT_OBJECT：对象已损坏，将关闭该对象句柄。\n
 *         TEE_ERROR_STORAGE_NOT_AVAILABLE：对象存储在当前不可访问的存储区域。
 * @since 20
 */
TEE_Result TEE_CopyObjectAttributes1(TEE_ObjectHandle destObject, TEE_ObjectHandlesrcObject);

/**
 * @brief 限制对象的 <b>objectUse</b> 位。
 *
 * 该位决定对象中密钥的使用方式。值的范围是Usage_Constant。\n
 * objectUse参数中的位可以如下设置：\n
 * 如果设置为1，对象中的相应使用标志保持不变。\n
 * 如果设置为0，则清除对象中的相应使用标志。\n
 * 新创建的对象包含所有Usage_Constant，并且只能清除使用标志。
 *
 * @param object 表示目标对象的 TEE_ObjectHandle。
 * @param objectUsage 表示新的对象使用方式。
 *
 * @return TEE_SUCCESS：操作成功。\n
 *         TEE_ERROR_CORRUPT_OBJECT：对象已损坏，将关闭该对象句柄。\n
 *         TEE_ERROR_STORAGE_NOT_AVAILABLE：对象存储在当前不可访问的存储区域。
 * @since 20
 */
TEE_Result TEE_RestrictObjectUsage1(TEE_ObjectHandle object, uint32_t objectUsage);

#ifdef __cplusplus
}
#endif

#endif
/** @} */